{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# 1. Activity Magic"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The Activity Magic is a method of giving quizzes, polls, etc. to a group of users on a jupyterhub server. \n",
"\n",
"In the current implementation, it acts like a Classroom Response System (also called \"clickers\", [audience response system](https://en.wikipedia.org/wiki/Audience_response), personal response systems, student response system, or electronic response system).\n",
"\n",
"The main pedagogical use is for implementing instantaneous anonymous polling for gaging student understanding."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Table of Contents\n",
"* [1. Activity Magic](#1.-Activity-Magic)\n",
"\t* [1.1 Requirements](#1.1-Requirements)\n",
"\t\t* [1.1.1 Install tl;dr](#1.1.1-Install-tl;dr)\n",
"\t* [1.2 Workflow](#1.2-Workflow)\n",
"\t* [1.3 Demonstration](#1.3-Demonstration)\n",
"\t* [1.4 JSON Details](#1.4-JSON-Details)\n",
"\t\t* [1.4.1 Top level](#1.4.1-Top-level)\n",
"\t\t* [1.4.2 Activity types](#1.4.2-Activity-types)\n",
"\t\t\t* [1.4.2.1 poll](#1.4.2.1-poll)\n",
"\t* [1.5 Results file format](#1.5-Results-file-format)\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 1.1 Requirements"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To use, you will need:\n",
"\n",
"* [jupyterhub](https://github.com/jupyter/jupyterhub) - for multi-user notebook server\n",
"* [metakernel](https://github.com/Calysto/metakernel/) - for the [activity magic](https://github.com/Calysto/metakernel/blob/master/metakernel/magics/activity_magic.py)\n",
"* [calysto](https://github.com/Calysto/calysto) - for barcharts"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### 1.1.1 Install tl;dr"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"1. Shell: pip install metakernel\n",
"2. Shell: pip install calysto\n",
"3. Notebook: from metakernel import register_ipython_magics\n",
"4. Notebook: register_ipython_magics()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 1.2 Workflow"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Activity magic works as follows:\n",
"\n",
"1. instructor creates a poll using the %%activity cell magic defining a poll via JSON\n",
"2. poll appears for verification\n",
"3. students use the same file, but via a line magic\n",
"4. everyone should make their choice\n",
"5. instructor shows bar chart of all choices\n",
"6. everyone clicks on \"Next\" to proceed to the next question"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 1.3 Demonstration"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Here is the docs on %%activity magic:"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [],
"source": [
"%%activity?"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"```\n",
"Docstring:\n",
"%%activity FILENAME - make an activity from\n",
" a JSON structure\n",
"\n",
"This magic will construct a Python file from the cell's\n",
"content, a JSON structure.\n",
"\n",
"Example:\n",
" %%activity /home/teacher/activity1\n",
" {\"activity\": \"poll\",\n",
" \"instructors\": [\"teacher01\"],\n",
" \"items\": [{\"id\": \"...\",\n",
" \"type\": \"multiple choice\",\n",
" \"question\": \"...\",\n",
" \"options\": [\"...\", ...]\n",
" }, ...]\n",
" }\n",
"\n",
"In this example, users will load\n",
"/home/teacher/activity1\n",
"File: /usr/lib/python3.4/site-packages/metakernel-0.10.5-py3.4.egg/metakernel/magics/activity_magic.py\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Here is an actual poll with three questions:"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [],
"source": [
"%%activity /home/dblank/activity1\n",
"\n",
"{\"activity\": \"poll\",\n",
" \"instructors\": [\"dblank\"],\n",
" \"items\": [\n",
" {\"id\": \"1\", \n",
" \"question\": \"\"\"Which of the following will print \"Hello\" 5 times without errors?\"\"\", \n",
" \"type\": \"multiple choice\",\n",
" \"options\": [\n",
"\"\"\"\n",
"for (int i=0; i < 5; i++) {\n",
" println(\"Hello\");\n",
"}\n",
"\"\"\",\n",
"\"\"\"\n",
"println(\"Hello\");\n",
"println(\"Hello\");\n",
"println(\"Hello\");\n",
"println(\"Hello\");\n",
"println(\"Hello\");\n",
"\"\"\",\n",
"\"\"\"\n",
"int i = 0;\n",
"while (i < 5) {\n",
" println(\"Hello\");\n",
" i++;\n",
"}\n",
"\"\"\",\n",
" \"All of the above\",\n",
" \"None of the above\",\n",
" ]},\n",
" \n",
" {\"id\": \"2\", \n",
" \"question\": \"\"\"Which of the following is a function definition?\"\"\", \n",
" \"type\": \"multiple choice\",\n",
" \"options\": [\n",
"\"\"\"\n",
"void draw() {\n",
"}\n",
"\"\"\",\n",
"\"\"\"\n",
"rect(10, 10, 50, 50);\n",
"\"\"\",\n",
"\"\"\"\n",
"drawBunny(mouseX, mouseY, 50, 100);\n",
"\"\"\",\n",
" \"All of the above\",\n",
" \"None of the above\",\n",
" ]},\n",
" {\"id\": \"3\", \n",
" \"question\": \"\"\"Which of the following has parameters?\"\"\", \n",
" \"type\": \"multiple choice\",\n",
" \"options\": [\n",
"\"\"\"\n",
"void draw() {\n",
"}\n",
"\"\"\",\n",
"\"\"\"\n",
"void drawRect(float x, float y, float w, float h) {\n",
" rect(x, y, w, h);\n",
"}\n",
"\"\"\",\n",
"\"\"\"\n",
"void drawBunny() {\n",
" rect(10, 20, 100, 150);\n",
"}\n",
"\"\"\",\n",
" \"All of the above\",\n",
" \"None of the above\",\n",
" ]},\n",
" {\"id\": \"4\", \n",
" \"question\": \"\"\"Which of the following is a function call?\"\"\", \n",
" \"type\": \"multiple choice\",\n",
" \"options\": [\n",
"\"\"\"\n",
"void draw() {\n",
"}\n",
"\"\"\",\n",
"\"\"\"\n",
"rect(10, 10, 50, 50);\n",
"\"\"\",\n",
"\"\"\"\n",
"drawBunny(mouseX, mouseY, 50, 100);\n",
"\"\"\",\n",
" \"2 and 3\",\n",
" \"None of the above\",\n",
" ]},\n",
" ]\n",
"}\n",
"\n",
"\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"When executed in a live cell, it shows the following:\n",
"\n",
"![](\"images/activity.png\")
\n",
"\n",
"Instructors in the list will be able to click on the \"Results\" button to show the barchart of choices.\n",
"\n",
"Students enter:"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"%activity /home/dblank/activity1"
]
},
{
"cell_type": "markdown",
"metadata": {
"collapsed": true
},
"source": [
"and are ready for discussing issues."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 1.4 JSON Details"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The activities are stored in a JSON-like format as follows."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### 1.4.1 Top level"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"```python\n",
"{\n",
" \"activity\": \"poll\",\n",
" \"instructors\": [\"userid\", ...],\n",
" \"items\": [...],\n",
" \"results_filename\": \"/home/user/results.txt\"\n",
"}\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"* **activity** is an activity type\n",
"* **instructors** is optional, and lists those user id's for which the \"Results\" button will appear.\n",
"* **item** is a list of items specific to this activity type\n",
"* **results_filename** is optional; if unspecified, it will be the name of the activity file + \".results\". The system will automatically create it and make it writable by everyone"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### 1.4.2 Activity types"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### 1.4.2.1 poll"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Poll has the following structure for an item:\n",
"\n",
"```python\n",
"{\n",
" \"id\": \"1\",\n",
" \"type\": \"multiple choice\",\n",
" \"question\": \"The actual question?\",\n",
" \"options\": [\"choice 1\", \"choice 2\", ...]\n",
"}\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Currently, all of the poll items are strings that will be rendered as HTML. Future plans include adding all widget types (LaTeX, text, etc.) The options are currently limited to 5 choices or less. Also, choices are listed as 1 through 5.\n",
"\n",
"* **id** is a unique string identification that you create\n",
"* **type** is a poll activity type\n",
"* **question** is the question to ask\n",
"* **options** is a list of the multiple choices"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 1.5 Results file format"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"```python\n",
"question id::user id::datetime::choice\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The barchart is rendered by [calysto's graphics](https://github.com/Calysto/calysto).\n",
"\n",
"Try it out! Feedback welcome!"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.6.1"
}
},
"nbformat": 4,
"nbformat_minor": 1
}